Skip to main content

Extension Template Catalog

Overview​

The extension template catalog is a remote, versioned list of Candescent-maintained starters for web widgets. Use these vetted project layouts when you want a faster path than a blank offline scaffold. The generator downloads the latest catalog, allows users to pick a template, and produces a runnable Nx Module Federation project under widgets/web/ wired for @cdx-extensions/di-sdk-web and the web harness.

note
  1. Run all commands below from your cdx-extensibility-apps (or FI monorepo) root.
  2. Use pnpm.
  3. Run pnpm run setup (or pnpm add @cdx-extensions/extension-generator-web if the generator is not already a workspace dependency).
  4. Run the Nx commands below with pnpm exec nx.
  5. For additional information, see pnpm run vs pnpm exec.

Browse the Catalog​

Templates are added to the catalog on an ongoing basis. See the full, up-to-date set at generation time (interactive prompts) or with the list command below.

Setup​

Bash
pnpm exec nx run list-web-widget-templates

This command fetches the same remote catalog the generators use and prints web widget entries grouped by category.

Example: Credit Score (Data Chart)​

Browse — category and template picker:

$ pnpm exec nx run generate-web-widget

? Choose a template category: › Data Chart
? Choose a template: › Credit Score — CDX web widget template (credit-score).
? Choose a name for your widget (kebab-case): › acme-credit-score
Interactive CLI prompts for choosing a web widget category and template

Outcome — generated widget in the web harness:

Credit Score widget with gauge, score factors, and recent history in the web harness

Example: Agent (Interactive)​

Browse — category and template picker:

$ pnpm exec nx run generate-web-widget

? Choose a template category: › Interactive
? Choose a template: › Agent — CDX web widget template (agent).
? Choose a name for your widget (kebab-case): › acme-agent
Interactive CLI prompts for choosing an interactive web widget template

Outcome — generated widget in the web harness:

Bring Your Own Agent widget with chat UI in the web harness
note

Template ids, categories, and counts change as Candescent publishes new starters. Use pnpm exec nx run list-web-widget-templates or the interactive generator for the current catalog.

Generate Your Extension​

Interactive (full flow)​

Bash
pnpm exec nx run generate-web-extensions

Equivalent:

Bash
pnpm exec nx g @cdx-extensions/extension-generator-web:extensions-from-template

Flow:

  1. Fetches the latest catalog from the remote URL (with cache and local fallbacks).
  2. Prompts for extension type (from catalog), then category, then template.
  3. Prompts for your widget name.
  4. Optionally prompts for an environment apiUrl when the template supports it.
  5. Downloads the selected npm template package and scaffolds the widget under widgets/web/<name>-widget/.

Widget only (skip type picker)​

Bash
pnpm exec nx run generate-web-widget

Equivalent:

Bash
pnpm exec nx g @cdx-extensions/extension-generator-web:widget
Workspace commandUnderlying generator
pnpm exec nx run generate-web-extensions@cdx-extensions/extension-generator-web:extensions-from-template
pnpm exec nx run generate-web-widget@cdx-extensions/extension-generator-web:widget

Non-Interactive / CI Usage​

Pass generator options after --:

Bash
pnpm exec nx run generate-web-widget -- --template=credit-score --name=acme-credit-score
pnpm exec nx run generate-web-widget -- --template=agent --name=acme-agent
OptionRequiredDescription
nameYesWidget slug in kebab-case
templateYesCatalog template id (discover ids with pnpm exec nx run list-web-widget-templates) or full npm package name
stackWidgetNotrue for stack-widget layout (default false)

What You Get​

In addition to widget source from the selected template package, the generator writes CDX project scaffold files:

  • .babelrc, .eslintrc.json
  • jest.config.ts, webpack.config.ts, module-federation.config.ts
  • project.json, tsconfig.json, tsconfig.app.json, tsconfig.spec.json

Widgets scaffold under widgets/web/<name>-widget/.

Scaffold templates ship in the generator package under dist/projectFiles/. When a published template package includes them under dist/, those versions take precedence.

Only modify files inside src/app/ for your widget logic and UI. See Getting Started for the full editability guide.

Advanced​

Optional reference for troubleshooting. Most users can skip this section.

Catalog source and cache​

On each run the generator syncs catalog/extension-templates.json in this order: remote URL → ~/.cdx/cache/catalog/extension-templates.json → local workspace catalog/extension-templates.json.

Clear ~/.cdx/cache/ after a platform publish if you need a fresh template overlay download.

note

Today the published web catalog is widget-only. The full-flow generator can prompt for other extension types when the catalog includes them; until then, use pnpm exec nx run generate-web-widget or pick widget in the interactive flow.

Next Steps​